<!DOCTYPE html>
<html id="docs" lang="en" class="">
	<head>
	<meta charset="utf-8">
<title>Labels and Selectors - Kubernetes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="shortcut icon" type="image/png" href="../../../../images/favicon.png">
<link rel="stylesheet" type="text/css" href="../../../../css/base_fonts.css">
<link rel="stylesheet" type="text/css" href="../../../../css/styles.css">
<link rel="stylesheet" type="text/css" href="https://code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.css">
<link rel="stylesheet" type="text/css" href="../../../../css/callouts.css">
<link rel="stylesheet" type="text/css" href="../../../../css/custom-jekyll/tags.css">




<meta name="description" content="Labels and Selectors" />
<meta property="og:description" content="Labels and Selectors" />

<meta property="og:url" content="https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/" />
<meta property="og:title" content="Labels and Selectors - Kubernetes" />

<script
src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script
src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
integrity="sha256-VazP97ZCwtekAsvgPBSUwPFKdrwD3unUfSGVYrahUqU="
crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.js"></script>
<script src="../../../../js/script.js"></script>
<script src="../../../../js/custom-jekyll/tags.js"></script>


	</head>
	<body>
		<div id="cellophane" onclick="kub.toggleMenu()"></div>

<header>
    <a href="../../../../index.html" class="logo"></a>

    <div class="nav-buttons" data-auto-burger="primary">
        <ul class="global-nav">
            
            
            <li><a href="../../../home.1">Documentation</a></li>
            
            <li><a href="../../../../blog/index.html">Blog</a></li>
            
            <li><a href="../../../../partners/index.html">Partners</a></li>
            
            <li><a href="../../../../community/index.html">Community</a></li>
            
            <li><a href="../../../../case-studies/index.html">Case Studies</a></li>
            
            
             <li>
                <a href="../../../user-guide/labels#">
                    English <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="../../../../zh/index.html">中文 Chinese</a></li>
                
                    <li><a href="../../../../ko/index.html">한국어 Korean</a></li>
                
                </ul>
            </li>
         
            <li>
                <a href="../../../user-guide/labels#">
                    v1.11 <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="https://kubernetes.io">v1.12</a></li>
                
                    <li><a href="../../../../index.html">v1.11</a></li>
                
                    <li><a href="https://v1-10.docs.kubernetes.io">v1.10</a></li>
                
                    <li><a href="https://v1-9.docs.kubernetes.io">v1.9</a></li>
                
                </ul>
            </li>
        </ul>
        
        <a href="../../../tutorials/kubernetes-basics/index.html" class="button" id="tryKubernetes" data-auto-burger-exclude>Try Kubernetes</a>
        <button id="hamburger" onclick="kub.toggleMenu()" data-auto-burger-exclude><div></div></button>
    </div>

    <nav id="mainNav">
        <main data-auto-burger="primary">
        <div class="nav-box">
            <h3><a href="../../../tutorials/stateless-application/hello-minikube/index.html">Get Started</a></h3>
            <p>Ready to get your hands dirty? Build a simple Kubernetes cluster that runs "Hello World" for Node.js.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../home.1">Documentation</a></h3>
            <p>Learn how to use Kubernetes with the use of walkthroughs, samples, and reference documentation. You can even <a href="../../../../editdocs/index.html" data-auto-burger-exclude>help contribute to the docs</a>!</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../community/index.html">Community</a></h3>
            <p>If you need help, you can connect with other Kubernetes users and the Kubernetes authors, attend community events, and watch video presentations from around the web.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../blog/index.html">Blog</a></h3>
            <p>Read the latest news for Kubernetes and the containers space in general, and get technical how-tos hot off the presses.</p>
        </div>
        </main>
        <main data-auto-burger="primary">
        <div class="left">
            <h5 class="github-invite">Interested in hacking on the core Kubernetes code base?</h5>
            <a href="https://github.com/kubernetes/kubernetes" class="button" data-auto-burger-exclude>View On Github</a>
        </div>

        <div class="right">
            <h5 class="github-invite">Explore the community</h5>
            <div class="social">
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>Twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
        </div>
        <div class="clear" style="clear: both"></div>
        </main>
    </nav>
</header>

		
		
		<section id="hero" class="light-text no-sub">
			









<h1>Concepts</h1>
<h5></h5>








<div id="vendorStrip" class="light-text">
	<ul>
		
		
		<li><a href="../../../home.1">DOCUMENTATION</a></li>
		
		
		<li><a href="../../../setup/index.html">SETUP</a></li>
		
		
		<li><a href="../../index.html" class="YAH">CONCEPTS</a></li>
		
		
		<li><a href="../../../tasks/index.html">TASKS</a></li>
		
		
		<li><a href="../../../tutorials/index.html">TUTORIALS</a></li>
		
		
		<li><a href="../../../reference.1">REFERENCE</a></li>
		
	</ul>
	<div id="searchBox">
		<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)" autofocus="autofocus">
	</div>
</div>

		</section>
		
		
<section id="deprecationWarning">
  <main>
    <div class="content deprecation-warning">
      <h3>
        Documentation for Kubernetes v1.11 is no longer actively maintained. The version you are currently viewing is a static snapshot.
        For up-to-date documentation, see the <a href="https://kubernetes.io/docs/home/">latest</a> version.
      </h3>
    </div>
  </main>
</section>


		<section id="encyclopedia">
			
<div id="docsToc">
     <div class="pi-accordion">
    	
        
        
        
        
        
         
             
                 
             
         
             
                 
             
         
             
                 
                          
                          
                 
             
         
             
         
             
         
             
         
             
         
             
         
         
        
        <a class="item" data-title="Concepts" href="../../index.html"></a>

	
	
		
		
	<div class="item" data-title="Overview">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="What is Kubernetes?" href="../index.html"></a>

		
	
		
		
<a class="item" data-title="Kubernetes Components" href="../components.1"></a>

		
	
		
		
<a class="item" data-title="The Kubernetes API" href="../kubernetes-api/index.html"></a>

		
	
		
		
	<div class="item" data-title="Working with Kubernetes Objects">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Understanding Kubernetes Objects" href="kubernetes-objects.1"></a>

		
	
		
		
<a class="item" data-title="Names" href="../../../user-guide/identifiers"></a>

		
	
		
		
<a class="item" data-title="Namespaces" href="namespaces.1"></a>

		
	
		
		
<a class="item" data-title="Labels and Selectors" href="../../../user-guide/labels"></a>

		
	
		
		
<a class="item" data-title="Annotations" href="annotations.1"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Object Management Using kubectl">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Kubernetes Object Management" href="../../../tutorials/object-management-kubectl/object-management/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Kubernetes Objects Using Imperative Commands" href="../../../tutorials/object-management-kubectl/imperative-object-management-command/index.html"></a>

		
	
		
		
<a class="item" data-title="Imperative Management of Kubernetes Objects Using Configuration Files" href="../../../tutorials/object-management-kubectl/imperative-object-management-configuration/index.html"></a>

		
	
		
		
<a class="item" data-title="Declarative Management of Kubernetes Objects Using Configuration Files" href="../../../tutorials/object-management-kubectl/declarative-object-management-configuration/index.html"></a>

		
	

		</div>
	</div>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Compute, Storage, and Networking Extensions">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Cluster Administration Overview" href="../../cluster-administration/cluster-administration-overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Certificates" href="../../cluster-administration/certificates/index.html"></a>

		
	
		
		
<a class="item" data-title="Cloud Providers" href="../../cluster-administration/cloud-providers/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Resources" href="../../cluster-administration/manage-deployment/index.html"></a>

		
	
		
		
<a class="item" data-title="Cluster Networking" href="../../../admin/networking"></a>

		
	
		
		
<a class="item" data-title="Logging Architecture" href="../../cluster-administration/logging.1"></a>

		
	
		
		
<a class="item" data-title="Configuring kubelet Garbage Collection" href="../../cluster-administration/kubelet-garbage-collection/index.html"></a>

		
	
		
		
<a class="item" data-title="Federation" href="../../cluster-administration/federation/index.html"></a>

		
	
		
		
<a class="item" data-title="Proxies in Kubernetes" href="../../cluster-administration/proxies/index.html"></a>

		
	
		
		
<a class="item" data-title="Controller manager metrics" href="../../cluster-administration/controller-metrics/index.html"></a>

		
	
		
		
<a class="item" data-title="Installing Addons" href="../../cluster-administration/addons/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Kubernetes Architecture">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Nodes" href="../../../admin/node.1"></a>

		
	
		
		
<a class="item" data-title="Master-Node communication" href="../../architecture/master-node-communication/index.html"></a>

		
	
		
		
<a class="item" data-title="Concepts Underlying the Cloud Controller Manager" href="../../architecture/cloud-controller/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Extending Kubernetes">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Extending your Kubernetes Cluster" href="../extending/index.html"></a>

		
	
		
		
	<div class="item" data-title="Extending the Kubernetes API">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Extending the Kubernetes API with the aggregation layer" href="../../api-extension/apiserver-aggregation.1"></a>

		
	
		
		
<a class="item" data-title="Custom Resources" href="../../api-extension/custom-resources/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Compute, Storage, and Networking Extensions">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Network Plugins" href="../../../admin/network-plugins/index.html"></a>

		
	
		
		
<a class="item" data-title="Device Plugins" href="../../cluster-administration/device-plugins.1"></a>

		
	

		</div>
	</div>

		
	
		
		
<a class="item" data-title="Service Catalog" href="../../service-catalog/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Containers">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Images" href="../../containers/images/index.html"></a>

		
	
		
		
<a class="item" data-title="Container Environment Variables" href="../../containers/container-environment-variables/index.html"></a>

		
	
		
		
<a class="item" data-title="Container Lifecycle Hooks" href="../../containers/container-lifecycle-hooks/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Workloads">
		<div class="container">
		
		
	
	
		
		
	<div class="item" data-title="Pods">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Pod Overview" href="../../workloads/pods/pod-overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Pods" href="../../../user-guide/pods/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Lifecycle" href="../../../user-guide/pod-states/index.html"></a>

		
	
		
		
<a class="item" data-title="Init Containers" href="../../abstractions/init-containers/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Preset" href="../../workloads/pods/podpreset/index.html"></a>

		
	
		
		
<a class="item" data-title="Disruptions" href="../../workloads/pods/disruptions/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Controllers">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="ReplicaSet" href="../../workloads/controllers/replicaset/index.html"></a>

		
	
		
		
<a class="item" data-title="ReplicationController" href="../../../user-guide/replication-controller/index.html"></a>

		
	
		
		
<a class="item" data-title="Deployments" href="../../workloads/controllers/deployment/index.html"></a>

		
	
		
		
<a class="item" data-title="StatefulSets" href="../../workloads/controllers/statefulset.md"></a>

		
	
		
		
<a class="item" data-title="DaemonSet" href="../../workloads/controllers/daemonset.1"></a>

		
	
		
		
<a class="item" data-title="Garbage Collection" href="../../workloads/controllers/garbage-collection/index.html"></a>

		
	
		
		
<a class="item" data-title="Jobs - Run to Completion" href="../../workloads/controllers/jobs-run-to-completion.1"></a>

		
	
		
		
<a class="item" data-title="CronJob" href="../../workloads/controllers/cron-jobs.1"></a>

		
	

		</div>
	</div>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Configuration">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Configuration Best Practices" href="../../configuration/overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Compute Resources for Containers" href="../../../user-guide/compute-resources/index.html"></a>

		
	
		
		
<a class="item" data-title="Assigning Pods to Nodes" href="../../../user-guide/node-selection/index.html"></a>

		
	
		
		
<a class="item" data-title="Taints and Tolerations" href="../../configuration/taint-and-toleration.1"></a>

		
	
		
		
<a class="item" data-title="Secrets" href="../../../user-guide/secrets.1"></a>

		
	
		
		
<a class="item" data-title="Organizing Cluster Access Using kubeconfig Files" href="../../configuration/organize-cluster-access-kubeconfig/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Priority and Preemption" href="../../configuration/pod-priority-preemption/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Services, Load Balancing, and Networking">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Services" href="../../../user-guide/services"></a>

		
	
		
		
<a class="item" data-title="DNS for Services and Pods" href="../../services-networking/dns-pod-service/index.html"></a>

		
	
		
		
<a class="item" data-title="Connecting Applications with Services" href="../../services-networking/connect-applications-service.1"></a>

		
	
		
		
<a class="item" data-title="Ingress" href="../../services-networking/ingress/index.html"></a>

		
	
		
		
<a class="item" data-title="Network Policies" href="../../services-networking/networkpolicies/index.html"></a>

		
	
		
		
<a class="item" data-title="Adding entries to Pod /etc/hosts with HostAliases" href="../../services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Storage">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Volumes" href="../../storage/volumes.1"></a>

		
	
		
		
<a class="item" data-title="Persistent Volumes" href="../../../user-guide/persistent-volumes/index.html"></a>

		
	
		
		
<a class="item" data-title="Storage Classes" href="../../storage/storage-classes.1"></a>

		
	
		
		
<a class="item" data-title="Dynamic Volume Provisioning" href="../../storage/dynamic-provisioning/index.html"></a>

		
	
		
		
<a class="item" data-title="Node-specific Volume Limits" href="../../storage/storage-limits/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Policies">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Resource Quotas" href="../../policy/resource-quotas/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Security Policies" href="../../../user-guide/pod-security-policy"></a>

		
	

		</div>
	</div>

		
	






     </div> 
    <button class="push-menu-close-button" onclick="kub.toggleToc()"></button>
</div> 

			<div id="docsContent">
				
<p><a href="../../../editdocs#docs/concepts/overview/working-with-objects/labels.md" id="editPageButton">Edit This Page</a></p>

<h1>Labels and Selectors</h1>



<p><em>Labels</em> are key/value pairs that are attached to objects, such as pods.
Labels are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system.
Labels can be used to organize and to select subsets of objects.  Labels can be attached to objects at creation time and subsequently added and modified at any time.
Each object can have a set of key/value labels defined.  Each Key must be unique for a given object.</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json"><span style="color:#b44">&#34;metadata&#34;</span><span style="">:</span> {
  <span style="color:#008000;font-weight:bold">&#34;labels&#34;</span>: {
    <span style="color:#008000;font-weight:bold">&#34;key1&#34;</span> : <span style="color:#b44">&#34;value1&#34;</span>,
    <span style="color:#008000;font-weight:bold">&#34;key2&#34;</span> : <span style="color:#b44">&#34;value2&#34;</span>
  }
}</code></pre></div>
<p>We&rsquo;ll eventually index and reverse-index labels for efficient queries and watches, use them to sort and group in UIs and CLIs, etc. We don&rsquo;t want to pollute labels with non-identifying, especially large and/or structured, data. Non-identifying information should be recorded using <a href="annotations.1">annotations</a>.</p>









<ul id="markdown-toc">










<li><a href="../../../user-guide/labels#motivation">Motivation</a></li>




<li><a href="../../../user-guide/labels#syntax-and-character-set">Syntax and character set</a></li>




<li><a href="../../../user-guide/labels#label-selectors">Label selectors</a></li>




<li><a href="../../../user-guide/labels#api">API</a></li>



















</ul>


<h2 id="motivation">Motivation</h2>

<p>Labels enable users to map their own organizational structures onto system objects in a loosely coupled fashion, without requiring clients to store these mappings.</p>

<p>Service deployments and batch processing pipelines are often multi-dimensional entities (e.g., multiple partitions or deployments, multiple release tracks, multiple tiers, multiple micro-services per tier). Management often requires cross-cutting operations, which breaks encapsulation of strictly hierarchical representations, especially rigid hierarchies determined by the infrastructure rather than by users.</p>

<p>Example labels:</p>

<ul>
<li><code>&quot;release&quot; : &quot;stable&quot;</code>, <code>&quot;release&quot; : &quot;canary&quot;</code></li>
<li><code>&quot;environment&quot; : &quot;dev&quot;</code>, <code>&quot;environment&quot; : &quot;qa&quot;</code>, <code>&quot;environment&quot; : &quot;production&quot;</code></li>
<li><code>&quot;tier&quot; : &quot;frontend&quot;</code>, <code>&quot;tier&quot; : &quot;backend&quot;</code>, <code>&quot;tier&quot; : &quot;cache&quot;</code></li>
<li><code>&quot;partition&quot; : &quot;customerA&quot;</code>, <code>&quot;partition&quot; : &quot;customerB&quot;</code></li>
<li><code>&quot;track&quot; : &quot;daily&quot;</code>, <code>&quot;track&quot; : &quot;weekly&quot;</code></li>
</ul>

<p>These are just examples of commonly used labels; you are free to develop your own conventions. Keep in mind that label Key must be unique for a given object.</p>

<h2 id="syntax-and-character-set">Syntax and character set</h2>

<p><em>Labels</em> are key/value pairs. Valid label keys have two segments: an optional prefix and name, separated by a slash (<code>/</code>).  The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character (<code>[a-z0-9A-Z]</code>) with dashes (<code>-</code>), underscores (<code>_</code>), dots (<code>.</code>), and alphanumerics between.  The prefix is optional.  If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (<code>.</code>), not longer than 253 characters in total, followed by a slash (<code>/</code>).
If the prefix is omitted, the label Key is presumed to be private to the user. Automated system components (e.g. <code>kube-scheduler</code>, <code>kube-controller-manager</code>, <code>kube-apiserver</code>, <code>kubectl</code>, or other third-party automation) which add labels to end-user objects must specify a prefix.  The <code>kubernetes.io/</code> prefix is reserved for Kubernetes core components.</p>

<p>Valid label values must be 63 characters or less and must be empty or begin and end with an alphanumeric character (<code>[a-z0-9A-Z]</code>) with dashes (<code>-</code>), underscores (<code>_</code>), dots (<code>.</code>), and alphanumerics between.</p>

<h2 id="label-selectors">Label selectors</h2>

<p>Unlike <a href="../../../user-guide/identifiers">names and UIDs</a>, labels do not provide uniqueness. In general, we expect many objects to carry the same label(s).</p>

<p>Via a <em>label selector</em>, the client/user can identify a set of objects. The label selector is the core grouping primitive in Kubernetes.</p>

<p>The API currently supports two types of selectors: <em>equality-based</em> and <em>set-based</em>.
A label selector can be made of multiple <em>requirements</em> which are comma-separated. In the case of multiple requirements, all must be satisfied so the comma separator acts as a logical <em>AND</em> (<code>&amp;&amp;</code>) operator.</p>

<p>An empty label selector (that is, one with zero requirements) selects every object in the collection.</p>

<p>A null label selector (which is only possible for optional selector fields) selects no objects.</p>

<blockquote class="note">
  <div><strong>Note</strong>: the label selectors of two controllers must not overlap within a namespace, otherwise they will fight with each other.</div>
</blockquote>

<h3 id="equality-based-requirement"><em>Equality-based</em> requirement</h3>

<p><em>Equality-</em> or <em>inequality-based</em> requirements allow filtering by label keys and values. Matching objects must satisfy all of the specified label constraints, though they may have additional labels as well.
Three kinds of operators are admitted <code>=</code>,<code>==</code>,<code>!=</code>. The first two represent <em>equality</em> (and are simply synonyms), while the latter represents <em>inequality</em>. For example:</p>

<pre><code>environment = production
tier != frontend
</code></pre>

<p>The former selects all resources with key equal to <code>environment</code> and value equal to <code>production</code>.
The latter selects all resources with key equal to <code>tier</code> and value distinct from <code>frontend</code>, and all resources with no labels with the <code>tier</code> key.
One could filter for resources in <code>production</code> excluding <code>frontend</code> using the comma operator: <code>environment=production,tier!=frontend</code></p>

<p>One usage scenario for equality-based label requirement is for Pods to specify
node selection criteria. For example, the sample Pod below selects nodes with
the label &ldquo;<code>accelerator=nvidia-tesla-p100</code>&rdquo;.</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">apiVersion:<span style="color:#bbb"> </span>v1<span style="color:#bbb">
</span><span style="color:#bbb"></span>kind:<span style="color:#bbb"> </span>Pod<span style="color:#bbb">
</span><span style="color:#bbb"></span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>name:<span style="color:#bbb"> </span>cuda-test<span style="color:#bbb">
</span><span style="color:#bbb"></span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>containers:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>-<span style="color:#bbb"> </span>name:<span style="color:#bbb"> </span>cuda-test<span style="color:#bbb">
</span><span style="color:#bbb">      </span>image:<span style="color:#bbb"> </span><span style="color:#b44">&#34;k8s.gcr.io/cuda-vector-add:v0.1&#34;</span><span style="color:#bbb">
</span><span style="color:#bbb">      </span>resources:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>limits:<span style="color:#bbb">
</span><span style="color:#bbb">          </span>nvidia.com/gpu:<span style="color:#bbb"> </span><span style="color:#666">1</span><span style="color:#bbb">
</span><span style="color:#bbb">  </span>nodeSelector:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>accelerator:<span style="color:#bbb"> </span>nvidia-tesla-p100</code></pre></div>
<h3 id="set-based-requirement"><em>Set-based</em> requirement</h3>

<p><em>Set-based</em> label requirements allow filtering keys according to a set of values. Three kinds of operators are supported: <code>in</code>,<code>notin</code> and <code>exists</code> (only the key identifier). For example:</p>

<pre><code>environment in (production, qa)
tier notin (frontend, backend)
partition
!partition
</code></pre>

<p>The first example selects all resources with key equal to <code>environment</code> and value equal to <code>production</code> or <code>qa</code>.
The second example selects all resources with key equal to <code>tier</code> and values other than <code>frontend</code> and <code>backend</code>, and all resources with no labels with the <code>tier</code> key.
The third example selects all resources including a label with key <code>partition</code>; no values are checked.
The fourth example selects all resources without a label with key <code>partition</code>; no values are checked.
Similarly the comma separator acts as an <em>AND</em> operator. So filtering resources with a <code>partition</code> key (no matter the value) and with <code>environment</code> different than  <code>qa</code> can be achieved using <code>partition,environment notin (qa)</code>.
The <em>set-based</em> label selector is a general form of equality since <code>environment=production</code> is equivalent to <code>environment in (production)</code>; similarly for <code>!=</code> and <code>notin</code>.</p>

<p><em>Set-based</em> requirements can be mixed with <em>equality-based</em> requirements. For example: <code>partition in (customerA, customerB),environment!=qa</code>.</p>

<h2 id="api">API</h2>

<h3 id="list-and-watch-filtering">LIST and WATCH filtering</h3>

<p>LIST and WATCH operations may specify label selectors to filter the sets of objects returned using a query parameter. Both requirements are permitted (presented here as they would appear in a URL query string):</p>

<ul>
<li><em>equality-based</em> requirements: <code>?labelSelector=environment%3Dproduction,tier%3Dfrontend</code></li>
<li><em>set-based</em> requirements: <code>?labelSelector=environment+in+%28production%2Cqa%29%2Ctier+in+%28frontend%29</code></li>
</ul>

<p>Both label selector styles can be used to list or watch resources via a REST client. For example, targeting <code>apiserver</code> with <code>kubectl</code> and using <em>equality-based</em> one may write:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ kubectl get pods -l <span style="color:#b8860b">environment</span><span style="color:#666">=</span>production,tier<span style="color:#666">=</span>frontend</code></pre></div>
<p>or using <em>set-based</em> requirements:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ kubectl get pods -l <span style="color:#b44">&#39;environment in (production),tier in (frontend)&#39;</span></code></pre></div>
<p>As already mentioned <em>set-based</em> requirements are more expressive.  For instance, they can implement the <em>OR</em> operator on values:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ kubectl get pods -l <span style="color:#b44">&#39;environment in (production, qa)&#39;</span></code></pre></div>
<p>or restricting negative matching via <em>exists</em> operator:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">$ kubectl get pods -l <span style="color:#b44">&#39;environment,environment notin (frontend)&#39;</span></code></pre></div>
<h3 id="set-references-in-api-objects">Set references in API objects</h3>

<p>Some Kubernetes objects, such as <a href="../../../user-guide/services"><code>services</code></a> and <a href="../../../user-guide/replication-controller"><code>replicationcontrollers</code></a>, also use label selectors to specify sets of other resources, such as <a href="../../../user-guide/pods">pods</a>.</p>

<h4 id="service-and-replicationcontroller">Service and ReplicationController</h4>

<p>The set of pods that a <code>service</code> targets is defined with a label selector. Similarly, the population of pods that a <code>replicationcontroller</code> should manage is also defined with a label selector.</p>

<p>Labels selectors for both objects are defined in <code>json</code> or <code>yaml</code> files using maps, and only <em>equality-based</em> requirement selectors are supported:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json"><span style="color:#b44">&#34;selector&#34;</span><span style="">:</span> {
    <span style="color:#008000;font-weight:bold">&#34;component&#34;</span> : <span style="color:#b44">&#34;redis&#34;</span>,
}</code></pre></div>
<p>or</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">selector:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>component:<span style="color:#bbb"> </span>redis</code></pre></div>
<p>this selector (respectively in <code>json</code> or <code>yaml</code> format) is equivalent to <code>component=redis</code> or <code>component in (redis)</code>.</p>

<h4 id="resources-that-support-set-based-requirements">Resources that support set-based requirements</h4>

<p>Newer resources, such as <a href="../../jobs/run-to-completion-finite-workloads/index.html"><code>Job</code></a>, <a href="../../workloads/controllers/deployment/index.html"><code>Deployment</code></a>, <a href="../../workloads/controllers/replicaset/index.html"><code>Replica Set</code></a>, and <a href="../../workloads/controllers/daemonset.1"><code>Daemon Set</code></a>, support <em>set-based</em> requirements as well.</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">selector:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>matchLabels:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>component:<span style="color:#bbb"> </span>redis<span style="color:#bbb">
</span><span style="color:#bbb">  </span>matchExpressions:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>-<span style="color:#bbb"> </span>{key:<span style="color:#bbb"> </span>tier,<span style="color:#bbb"> </span>operator:<span style="color:#bbb"> </span>In,<span style="color:#bbb"> </span>values:<span style="color:#bbb"> </span>[cache]}<span style="color:#bbb">
</span><span style="color:#bbb">    </span>-<span style="color:#bbb"> </span>{key:<span style="color:#bbb"> </span>environment,<span style="color:#bbb"> </span>operator:<span style="color:#bbb"> </span>NotIn,<span style="color:#bbb"> </span>values:<span style="color:#bbb"> </span>[dev]}</code></pre></div>
<p><code>matchLabels</code> is a map of <code>{key,value}</code> pairs. A single <code>{key,value}</code> in the <code>matchLabels</code> map is equivalent to an element of <code>matchExpressions</code>, whose <code>key</code> field is &ldquo;key&rdquo;, the <code>operator</code> is &ldquo;In&rdquo;, and the <code>values</code> array contains only &ldquo;value&rdquo;. <code>matchExpressions</code> is a list of pod selector requirements. Valid operators include In, NotIn, Exists, and DoesNotExist. The values set must be non-empty in the case of In and NotIn. All of the requirements, from both <code>matchLabels</code> and <code>matchExpressions</code> are ANDed together &ndash; they must all be satisfied in order to match.</p>

<h4 id="selecting-sets-of-nodes">Selecting sets of nodes</h4>

<p>One use case for selecting over labels is to constrain the set of nodes onto which a pod can schedule.
See the documentation on <a href="../../../user-guide/node-selection/index.html">node selection</a> for more information.</p>
















				<div class="issue-button-container">
					<p><a href="../../../user-guide/labels"><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/concepts/overview/working-with-objects/labels.md?pixel" alt="Analytics" /></a></p>
					
					
					<script type="text/javascript">
					PDRTJS_settings_8345992 = {
					"id" : "8345992",
					"unique_id" : "\/docs\/concepts\/overview\/working-with-objects\/labels\/",
					"title" : "Labels and Selectors",
					"permalink" : "https:\/\/kubernetes.io\/docs\/concepts\/overview\/working-with-objects\/labels\/"
					};
					(function(d,c,j){if(!document.getElementById(j)){var pd=d.createElement(c),s;pd.id=j;pd.src=('https:'==document.location.protocol)?'https://polldaddy.com/js/rating/rating.js':'http://i0.poll.fm/js/rating/rating.js';s=document.getElementsByTagName(c)[0];s.parentNode.insertBefore(pd,s);}}(document,'script','pd-rating-js'));
					</script>
					<a href="../../../user-guide/labels" onclick="window.open('https://github.com/kubernetes/website/issues/new?title=Issue%20with%20' +
					'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
					
					
					
					<a href="../../../editdocs#docs/concepts/overview/working-with-objects/labels.md" class="button issue">Edit this Page</a>
					
				</div>
			</div>
		</section>
		<footer>
    <main class="light-text">
        <nav>
            
            
            
            <a href="../../../home.1">Documentation</a>
            
            <a href="../../../../blog/index.html">Blog</a>
            
            <a href="../../../../partners/index.html">Partners</a>
            
            <a href="../../../../community/index.html">Community</a>
            
            <a href="../../../../case-studies/index.html">Case Studies</a>
            
        </nav>
        <div class="social">
            <div>
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
            </div>
            <div>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
            <div>
                <a href="../../../getting-started-guides/index.html" class="button">Get Kubernetes</a>
                <a href="https://git.k8s.io/community/contributors/guide" class="button">Contribute</a>
            </div>
        </div>
        <div id="miceType" class="center">
            &copy; 2018 The Kubernetes Authors | Documentation Distributed under <a href="https://git.k8s.io/website/LICENSE" class="light-text">CC BY 4.0</a>
        </div>
        <div id="miceType" class="center">
            Copyright &copy; 2018 The Linux Foundation&reg;. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage" class="light-text">Trademark Usage page</a>
        </div>
    </main>
</footer>

		<button class="flyout-button" onclick="kub.toggleToc()"></button>

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-36037335-10', 'auto');
ga('send', 'pageview');


(function () {
    window.addEventListener('DOMContentLoaded', init)

        
        function init() {
            window.removeEventListener('DOMContentLoaded', init)
                hideNav()
        }

    function hideNav(toc){
        if (!toc) toc = document.querySelector('#docsToc')
        if (!toc) return
            var container = toc.querySelector('.container')

                
                if (container) {
                    if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) {
                        toc.style.display = 'none'
                            document.getElementById('docsContent').style.width = '100%'
                    }
                } else {
                    requestAnimationFrame(function () {
                        hideNav(toc)
                    })
                }
    }
})();
</script>



	</body>
</html>